home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C++ / Libraries / CModalProgress / Read Me < prev    next >
Encoding:
Text File  |  1994-09-01  |  5.3 KB  |  146 lines  |  [TEXT/ttxt]
  1. CModalProgress            Read Me
  2. --------------            -------
  3.  
  4. Version 1.0
  5. 1 September 1994
  6.  
  7. © 1994 Alysoft Solutions. All rights reserved.
  8.  
  9. The accompanying source code is released as 'freeware'. And as such you
  10. are free to use it in any way that you see fit. The only exception is
  11. that you cannot sell for profit, the source on its own. It is ok to use
  12. the source in other products which are then sold for profit.
  13.  
  14. Items in this Archive
  15. ---------------------
  16.  
  17. Read Me - This file
  18. CModalProgress.cp - The class source
  19. CModalProgress.h - The classes header file
  20. ProgressDialog.rsrc - The required resourcess for the class
  21.  
  22. CTestDialogs.cp - Example source code
  23. CTestDialogs.h - Header file for examples
  24. main.cp - Main application code for example
  25. TestResources.rsrc - Resources for example
  26.  
  27. ProgressDialog - Example application
  28.  
  29. Description
  30. ----------
  31.  
  32. The CModalProgress class provides a standard interface for displaying a
  33. Modal dialog during a time intensive task. The progress of the task can
  34. be displayed in the dialog in one of three ways:
  35.   
  36.         • Textual representation of the percent complete
  37.         • A progress bar growing to the right as the task progresses
  38.         • An infinite progress bar (as used by the Finders 'Find' command)
  39.  
  40. Dialog Creation
  41. --------------
  42.  
  43. The visual appearance of the dialog used by the CModalProgress task is
  44. generated in a standard DLOG and DITL resource. There are several
  45. important items to note:
  46.  
  47.           • Item 1 must be an OK equivalent button
  48.           • Item 2 must be a CANCEL equivalent button
  49.           • Item 3 must be a user item for the OK button outline
  50.  
  51. These items are required for standard keyboard mappings. ie. the OK
  52. button will be activated when Enter or Return are pressed. The CANCEL
  53. button will be activated when ESC or Command-. are pressed.
  54. If this functionality is not required, the buttons should still be
  55. created but they should be disabled and the hidden away from view.
  56.  
  57. If a progress bar or infinite progress bar are required, a user item
  58. should be created for the bar to be drawn into. This item is then passed
  59. to the SetProgressBar() or SetInfiniteBar() methods.
  60.  
  61. If a textual progress indicator is required,  a static text item should
  62. be generated for this purpose. The item number for this static text is
  63. then passed to the SetPercentText() method along with the frequency at
  64. which you want the number to be updated. ed every 1% every 5% every 20%
  65. etc (would take values of 1, 5, 20 repectively). Make sure that this
  66. item is Enabled. If it is not, it will not be used by the clase.
  67.  
  68. Class Use
  69. ---------
  70.  
  71. The progress class breaks the task into separate states each state taking
  72. up a certain percentage of the total task time (except for the infinite
  73. progress bar).
  74.  
  75. Each state contains a resolution or a state space that is set as the task
  76. progresses. eg The Finder's Copy command whould have a read and then a
  77. write state. The state space may correspond to the size of the file, the
  78. copy command would increment the current state value each block that was
  79. read and then written.
  80.  
  81. eg. The Finder Copy Command.
  82.  
  83.       Copying one file that is 128k in size.
  84.  
  85.       • Generate CModalProgress object
  86.       • Provide DLOG resource ID
  87.       • call SetProgressBar() with the user item of the progress bar
  88.       • call SetCurrentState(50), 50 being 50% of total tasks as the first 
  89.         thing we will do is the reading which takes half of the time.
  90.       • call SetStateSpace(128), 128 is our state space. As we read in each 
  91.         1k block of the file we will increment the state value, when it
  92.         reaches 128 we are done.
  93.       • call BeginModal(), start the ball rolling...Show the window.
  94.       • Do read processing, calling SetCurrentStateValue() each block we 
  95.         read.
  96.  
  97. Repeat similar for thw write processing
  98.  
  99.       • call SetCurrentState(100), this state goes from 50 up to 100 %
  100.       • call SetStateSpace(128), representing the 128k of data
  101.       • Do the write processing.
  102.       • call EndModal()
  103.       • delete the CModalProgress object
  104.  
  105. The state space for the current state should be set to any value that is
  106. directly related to the processing task. As in the above example, the
  107. state space was set 128 as the data being read in was going to be 128k.
  108. Or if you are processing a text file, the state space may be the number
  109. of lines to process. Then each line that is processed, the modalprogress
  110. object is notified and it updates the progress bar or text accordingly.
  111.  
  112. Other Information
  113. ----------------
  114.  
  115. Forming part of this archive is a small application showing several
  116. examples of how to use the CModalProgress class. The code for these
  117. examples is included for further reference.
  118.  
  119. Registration
  120. -----------
  121.  
  122. As previously stated, this software is 'freeware'. However, if you wish
  123. to register with me that you are using this package, I can forward any
  124. modifications, bug fixes etc to you as soon as they are available.
  125.  
  126. Also, if you find any bugs in the code you can forward reports to me and
  127. will eventually receive updates to fix the problems.
  128.  
  129. Any other form of criticism, suggestions etc will be most welcome.
  130.  
  131. Contact Address
  132. ---------------
  133.  
  134. Postal:
  135.                  Alysoft Solutions
  136.                  PO Box 387
  137.                  Wollongong East
  138.                  New South Wales      2520
  139.                  Australia.
  140.  
  141. E-Mail:
  142.                  heathcot@bnr.ca
  143.  
  144. Phone:
  145.                  61-42-841400    (think about the timezone first!!)
  146.